Controle MQTT ao vivo

dica

O controle MQTT ao vivo é destinado para controle ao vivo. Para enviar agendamentos antecipadamente, veja Controle MQTT Agendado em vez disso.

Este guia irá ajudá-lo a configurar MQTT em seu SmartgridOne Controller para controlar e monitorar remotamente instalações de bateria e painéis solares.

O que você precisa

1. SmartgridOne Controller com conectividade à internet.
2. Credenciais MQTT: Isso pode ser solicitado enviando um email para support@eniris.be.
3. Ambiente de desenvolvimento Python (ou qualquer outro cliente MQTT). Este guia usa um exemplo básico escrito em Python para te ajudar a começar com MQTT e envio de comandos. Recomendamos utilizar Python pela facilidade de uso, mas qualquer outro cliente MQTT é suportado.

Informações extras

MQTT é um protocolo de comunicação rápida pela internet. É um sistema de mensagens de publicação/assinatura, que permite uma conexão direta entre sua máquina e o SmartgridOne Controller. Seus ativos são classificados em grupos de solar, bateria, EV e HVAC.

Configuração inicial (Ponto de partida para novos usuários)

Eu tenho um SmartgridOne Controller que eu gostaria de configurar para Controle Remoto MQTT.

1. Verifique sua rede

Certifique-se de que sua rede permite tráfego de rede mqtt pela porta 1883. Você pode fazer isso usando o comando:

nc -zv mqtt.eniris.be 1883

Quando este comando não estiver disponível, você pode alternativamente baixar e executar este código python.

Quando em dúvida, consulte seu engenheiro de rede ou use temporariamente o hotspot 4G/5G do seu telefone quando ocorrerem erros de conexão.

nota

Quando a porta 1883 não estiver acessível a partir da sua rede, oferecemos uma alternativa na porta 80. Isso pode ser configurado no seu cliente MQTT em um passo posterior deste manual.

2. Adicione seus dispositivos

Faça login na interface de comissionamento e certifique-se de que os dispositivos estão adicionados ao SmartgridOne Controller.

3. Adicione o sinal externo MQTT

4. Habilite o sinal remoto MQTT

O campo 'VPP ID' deve ser deixado em branco.

O tempo limite do mecanismo de fallback informa ao SmartgridOne Controller quanto tempo ele deve esperar por novos comandos. Quando o SmartgridOne Controller para de receber comandos, ele automaticamente adota a estratégia padrão após esse tempo limite.

Depois, selecione todos os dispositivos que você gostaria de incluir no Controle Remoto MQTT.

5. O sinal remoto foi adicionado

A interface de Controle Remoto MQTT foi ativada no SmartgridOne Controller.

Agora estamos prontos para enviar alguns comandos básicos usando um exemplo simples. A coluna Status informa se algum comando está ativo.

Script de demonstração em Python

Um bom ponto de partida seria testar sua nova integração configurada com um exemplo simples.

Este código de teste realiza uma tarefa simples de enviar continuamente os seguintes comandos:

• Bateria: Carregar a 5 kW
• Solar: Definir potência para 0 kW

O SmartgridOne Controller responde continuamente com uma mensagem de 'feedback' contendo os valores de potência observados na rede e nos ativos. Este recurso também está incluído neste exemplo.

Baixe o arquivo abaixo em seu IDE Python preferido. Preencha seu número de série e credenciais MQTT e execute o script:

Quando o acima for bem-sucedido, você pode continuar enviando outros tipos de comandos. Todos os comandos estão descritos em nossa Documentação de Controle Remoto MQTT.

Documentação MQTT para Envio de Comandos

Esta seção detalha o formato de mensagem MQTT e os requisitos de payload para controlar remotamente as políticas de potência em dispositivos dentro da rede do SmartgridOne Controller.

Tópico MQTT

O tópico MQTT usado para enviar comandos é estruturado da seguinte forma:

standard1/rp_one_s/remoteControlMetrics/'controller SN'

Onde 'controller SN' deve ser substituído pelo número de série real do SmartgridOne Controller que você pretende controlar.

Estrutura de Payload MQTT

Os comandos são enviados como payloads JSON. A estrutura do payload é projetada para especificar várias políticas de gerenciamento de potência e pontos de ajuste para diferentes componentes do sistema de rede inteligente. Aqui está o esboço do payload com descrições detalhadas dos campos:

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": "<Timestamp Unix>",
    "fields": {
        "<Component Policy>": "<Tipo de Política>",
        "<Component Power Setpoint>": <Ponto de ajuste em watts>
    }
}

Descrição dos campos

dica

Vários tipos de dispositivos (por exemplo, baterias + solar) podem ser controlados ao mesmo tempo.

• extraTags (Objeto):
  • nodeId (String): Um identificador único para o nó dentro da rede do SmartgridOne Controller. Isto é igual ao seu número de série, seguido por '_site_0' para a maioria dos dispositivos SmartgridOne Controller.
• time (Integer): Timestamp Unix em segundos indicando o momento em que a mensagem é enviada.
• fields (Objeto):
  • <Component>_policy (String): Tipo de política para o componente. É opcional e se não for especificado, o sistema irá utilizar a configuração padrão do SmartgridOne Controller.
  • <Component>_power_setpoint_w (Float): Ponto de ajuste de potência desejado em watts para o componente. Isso é opcional e somente relevante se uma política correspondente for especificada.

Componentes e Políticas

info

Ativos do mesmo tipo (por exemplo, duas baterias) serão combinados como um componente. Por exemplo, quando duas baterias de 5 kWh são instaladas, elas serão tratadas como uma bateria de 10 kWh.

Cada componente no objeto fields pode incluir uma política e um ponto de ajuste de potência. Os seguintes componentes podem ser controlados:

• solar_policy e solar_power_setpoint_w:

  • Controla a política de geração de energia solar e o ponto de ajuste. Políticas suportadas:
    • Política de ponto de ajuste: Definir a potência máxima produzida por todas as instalações solares conectadas combinadas. O campo solar_power_setpoint_w deve ser definido para o limite de produção em watts.
    • Política de restrição de alimentação: Produzir em plena potência, seguindo os limites atuais da rede.
    • Política de custo: Habilita a minimização do custo de preço antecipado (mercado EPEX Spot) na produção solar. Quando ocorrem preços de injeção negativos, nós reduzimos a produção para o consumo próprio. Quando tanto o preço de retirada quanto o preço de injeção são negativos, desligamos todas as instalações solares. O campo solar_power_setpoint_w é ignorado.
    • Política desligada: Desabilita toda interação para todos os ativos solares. Atenção: os limites não estão sendo protegidos neste modo. O campo solar_power_setpoint_w é ignorado.

• storage_policy e storage_power_setpoint_w:

• Controla a política do sistema de armazenamento de energia e a taxa de descarga ou carga de potência.

  • Configuração da política: Defina a potência total de carga (ponto de ajuste positivo) ou potência de descarga (ponto de ajuste negativo) para o grupo de baterias. Quando múltiplas baterias estão conectadas, o ponto de ajuste é dividido pela potência de carga/descarrega disponível para estressar igualmente as baterias. O campo storage_power_setpoint_w é definido para a potência desejada da bateria.
  • Custo da política: Habilita a otimização de custo de preço antecipado (mercado EPEX Spot) nas baterias, carregando durante as horas baratas e utilizando a energia nas horas caras. O campo storage_power_setpoint_w é ignorado.
  • Autoconsumo da política: Habilita um algoritmo simples de autoconsumo nas baterias. A produção solar em excesso é armazenada na bateria e, quando o sol não brilha, a energia é retirada da bateria. O campo storage_power_setpoint_w é ignorado.
  • Política desligada: Desabilita toda a interação para todos os ativos das baterias. Aviso: os limites não estão sendo monitorados neste modo. O campo storage_power_setpoint_w é ignorado.

• heat_pump_policy:

  • Alterna os sistemas de bomba de calor liga/desliga. Os tempos mínimos e máximos de ativação serão sempre respeitados.
    • Custo da política: Habilita a otimização de custo de preço antecipado (mercado EPEX Spot) nas bombas de calor. O algoritmo de precificação dinâmica local decide os melhores períodos de ativação.
    • Autoconsumo da política: Liga as bombas de calor se uma produção excessiva de energia solar for gerada.
    • Política desligada: Desliga as bombas de calor.
    • Política ligada: Liga as bombas de calor.

• switched_load_policy:

  • Alterna sistemas controlados por relé liga/desliga. Isso pode ser o relé embutido ou relés conectados à rede.
    • Custo da política: Habilita a otimização de custo de preço antecipado (mercado EPEX Spot) no relé.
    • Autoconsumo da política: Liga o relé se uma produção excessiva de energia solar for gerada.
    • Política desligada
    • Política ligada

• variable_power_load_policy e variable_power_load_power_setpoint_w:

  • Gerencia a política de consumo de potência de veículo elétrico e o ponto de ajuste.
    • Configuração da política: Defina a potência total de carga para o grupo de VE. O campo variable_power_load_power_setpoint_w é definido para a potência de carga desejada.
    • Custo da política: Habilita a otimização de custo de preço antecipado (mercado EPEX Spot) nas baterias, carregando durante as horas baratas. O campo variable_power_load_power_setpoint_w é ignorado.
    • Autoconsumo da política: Habilita a carga se uma produção excessiva de energia solar for gerada. O campo variable_power_load_power_setpoint_w é ignorado.
    • Política desligada: Desabilita toda a interação para todos os ativos de VE. O campo variable_power_load_power_setpoint_w é ignorado.

• site_policy e site_power_setpoint_w:

  • Gerencia os limites de exportação do local.
    • Exportação da política: Defina o limite de exportação para o local. O campo site_power_setpoint_w é definido para o limite de exportação.
    • Política padrão: Reverte o limite do local para a potência de exportação padrão, definida na configuração do controlador.

Controle de Dispositivos

Dispositivos específicos também podem ser controlados, em vez de grupos de dispositivos com base em seus tipos. A mensagem é estruturada de forma idêntica:

• nodeId_policy e nodeId_power_setpoint_w

info

Quando dois comandos são enviados para o mesmo ativo (por exemplo, um comando específico de dispositivo para um inversor solar e um comando para todos os dispositivos solares), o método de controle específico do dispositivo terá prioridade sobre o controle de tipo de dispositivo.

Comportamento de fallback

Para cada componente, se a política _policy e _power_setpoint_w não forem especificadas, o sistema usará automaticamente a política de fallback configurada no SmartgridOne Controller. Isso garante que cada dispositivo ou grupo de dispositivos opere de forma segura e continue a funcionar mesmo se instruções específicas não forem fornecidas.

Se nenhum comando estiver sendo enviado, após 60 segundos (ou o período de tempo configurado), as políticas padrão para os ativos serão reativadas.

Exemplo de carga útil

Abaixo está um exemplo de carga útil para definir várias políticas e pontos de ajuste:

{
    "extraTags": {
        "nodeId": "OM12404080000000000_site_0"
    },
    "time": 1714652046,
    "fields": {
        "solar_policy": "setpoint",
        "solar_power_setpoint_w": 5000,
        "storage_policy": "setpoint",
        "storage_power_setpoint_w": -5000
    }
}

Neste exemplo, a potência solar é definida para gerar até 5000 watts, e o sistema de armazenamento de energia é definido para carregar ou descarregar a uma taxa de 5000 watts, dependendo do sinal do valor do ponto de ajuste. Se a solar_policy ou a storage_policy forem omitidas, o respectivo dispositivo reverterá para as configurações padrão determinadas pelo SmartgridOne Controller.

Documentação MQTT para Receber feedback

Esta seção descreve a estrutura e o conteúdo das mensagens de feedback enviadas pelo SmartgridOne Controller via MQTT. Essas mensagens são publicadas no tópico standard1/outbound/remoteControlMetrics/feedback/<Controller SN> após um comando ter sido processado.

Tópico de Feedback MQTT

O tópico de feedback MQTT é estruturado da seguinte forma:

standard1/outbound/remoteControlMetrics/feedback/<Controller SN>

Onde <Controller SN> deve ser substituído pelo número de série do SmartgridOne Controller que está enviando o feedback.

Estrutura da Carga Útil de Feedback MQTT

nota

Todos os ativos são agrupados por seu tipo. Isso significa que duas instalações solares individuais de 3 kW serão tratadas como um ativo de 6 kW.

As mensagens de feedback são formatadas como cargas úteis JSON. Essas cargas úteis fornecem feedback detalhado sobre o estado do sistema após a aplicação dos comandos de ponto de ajuste, considerando limites de rede/dispositivo. Abaixo está a estrutura da carga útil de feedback com descrições de seus campos:

{
    "time": "<Unix Timestamp>",
    "data": {
        "state": {
            "grid": {
                "active_power_W": <Potência Ativa da Rede em Watts>,
                "today_imported_energy_Wh": <Energia Importada pela Rede em Watt-horas>,
                "today_exported_energy_Wh": <Energia Exportada pela Rede em Watt-horas>,
                "import_limit_W": <Limite de Importação da Rede em Watts>,
                "export_limit_W": <Limite de Exportação da Rede em Watts>,
            },
            "vpp_id": "<Identificador da Usina Solar Virtual>",
            "storage": {
                "energy_stored_Wh": <Energia Armazenada em Watt-horas>,
                "energy_capacity_Wh": <Capacidade Total de Energia em Watt-horas>,
                "mean_soc_perc": <Porcentagem Média de Estado de Carga>,
                "active_power_W": <Potência Ativa em Watts>,
                "executed_power_W": <Ponto de Ajuste de Potência Enviado para os Dispositivos em Watts>,
                "executed_policy": <Política Executada pelo Controlador>,
                "max_charge_power_W": <Potência Máxima de Carga em Watts>,
                "max_discharge_power_W": <Potência Máxima de Descarga em Watts>,
                "today_charged_Wh": <Energia Carregada no Dia Atual em Watt-horas>,
                "today_discharged_Wh": <Energia Descarregada no Dia Atual em Watt-horas>,
                "nr_devices": <Número de Dispositivos de Armazenamento Controlados Instalados>
            },
            "solar": {
                "active_power_W": <Potência Ativa Solar em Watts>,
                "executed_power_W": <Ponto de Ajuste de Potência Enviado para os Dispositivos em Watts>,
                "executed_policy": <Política Executada pelo Controlador>,
                "capacity_W": <Capacidade Solar em Watts>,
                "today_energy_Wh": <Energia Produzida Hoje em Watt-hora>.
                "nr_devices": <Número de Dispositivos Solares Controlados Instalados>
            },
            "heat_pump": {
                "executed_policy": <Política Executada pelo Controlador>,
                "operation_modes": <Modos de Operação da Bomba de Calor>,
                "executed_power_W": <Ponto de Potência Definido Enviado para Dispositivos em Watts>,
                "nr_devices": <Número de Dispositivos de Bomba de Calor Controlados Instalados>
            },
            "switched_load": {
                "executed_policy": <Política Executada pelo Controlador>,
                "devices_on": <Número de Dispositivos Ligados>,
                "devices_off": <Número de Dispositivos Desligados>,
                "executed_power_W": <Ponto de Potência Definido Enviado para Dispositivos em Watts>,
                "nr_devices": <Número de Dispositivos de Carga Alternada Controlados Instalados>  
            }
        },
        "response_code": <Código de Resposta>
    },
    "fields": {},
    "requestTime": "<Timestamp Unix>",
    "time": "<Timestamp Unix>",
    "siteNodeId": "<Controlador SN>_site_0"
}

### Descrição dos Campos
- time (Inteiro): Timestamp Unix indicando o momento em que a mensagem de feedback foi enviada.
- fields (Objeto):
    - state (Objeto):
        - vpp_id (String): Identificador para a Usina de Energia Virtual associada a este dispositivo.
        - grid (Objeto):
            - active_power_W (Float): Representa a potência ativa atual na rede em watts.
            - today_imported_energy_Wh (Float): A energia total retirada da rede hoje em watt-horas. Nota: Hoje é fornecido em horário UTC.
            - today_exported_energy_Wh (Float): A energia total injetada de volta na rede hoje em watt-horas. Nota: Hoje é fornecido em horário UTC.
            - import_limit_W (Float): O limite de importação da rede em watts,
            - export_limit_W (Float): O limite de exportação da rede em watts,
        - storage (Objeto):
            - energy_stored_Wh (Float): Quantidade atual de energia armazenada em watt-horas.
            - energy_capacity_Wh (Float): Capacidade total de energia do sistema de armazenamento em watt-horas.
            - mean_soc_perc (Float): Estado de carga como uma porcentagem. Esta é a média ponderada entre todas as baterias conectadas. (quando múltiplas baterias estão conectadas: por exemplo, a bateria 'a' tem uma capacidade de energia de 10 kWh e um estado de carga de 20%; a bateria 'b' tem uma capacidade de energia de 20 kWh e um estado de carga de 50%, então o mean_soc_perc é 40%)
            - active_power_W (Float): Potência ativa atual para o sistema de armazenamento em watts, mostrando a taxa de carga ou descarga.
            - max_charge_power_W (Float): Potência máxima na qual o armazenamento pode ser carregado.
            - max_discharge_power_W (Float): Potência máxima na qual o armazenamento pode ser descarregado.
            - executed_power_W (Float): A soma da potência total solicitada para (des)carregar dos ativos de armazenamento, sendo enviada pelo nosso algoritmo de controle. Aplicável apenas se a política 'follow_setpoint' estiver ativa.
            - executed_policy (Str): As políticas que foram aplicadas aos controláveis.
            - today_charged_Wh (Float): A energia total carregada nos ativos de bateria controláveis hoje. Nota: Hoje é fornecido em horário UTC.
            - today_charged_Wh (Float): A energia total carregada nos ativos de bateria controláveis hoje. Nota: Hoje é fornecido em horário UTC.
            - today_discharged_Wh (Float): A energia total descarregada dos ativos de bateria controláveis hoje. Nota: Hoje é fornecido em horário UTC.
            - nr_devices (Int): O número de ativos de bateria controláveis.
        - solar (Objeto):
            - active_power_W (Float): Potência ativa atual gerada por painéis solares em watts.
            - capacity_W (Float): Capacidade total do sistema de geração solar em watts.
            - executed_power_W (Float): A soma da potência total solicitada dos ativos solares, sendo enviada pelo nosso algoritmo de controle. Aplicável apenas se a política 'follow_setpoint' estiver ativa.
            - executed_policy (Str): As políticas que foram aplicadas aos controláveis.
            - today_energy_Wh (Float): A energia total produzida a partir dos ativos solares controláveis hoje. Nota: Hoje é fornecido em horário UTC.
            - nr_devices (Int): O número de ativos solares controláveis.
        - heat_pump (Objeto):
            - executed_policy (Str): As políticas que foram aplicadas aos controláveis.
            - operation_modes (Str): O modo da bomba de calor (Modo de Bloqueio, Modo de Impulso, Modo de Controle Próprio)
            - executed_power_W (Float): A potência esperada que está utilizando atualmente.
            - nr_devices (Int): O número de bombas de calor controláveis.
        - switched_load (Objeto):
            - executed_policy (Str): As políticas que foram aplicadas aos controláveis.
            - devices_on (Int): O número de dispositivos ligados.
            - devices_off (Int): O número de dispositivos desligados.
            - executed_power_W (Float): A potência que está utilizando atualmente (se disponível).
            - nr_devices (Int): O número de cargas alternadas controláveis ligadas/desligadas.
        - nodeId (Objeto):
            - Se um nodeId estiver incluído no comando, o feedback conterá o estado correspondente do dispositivo.
    - response_code (Int):
        - Indica o status da operação. Um response_code de 0 geralmente significa sucesso, enquanto outros valores podem indicar diferentes tipos de erros ou informações de status (estes devem ser detalhados em uma referência separada).

### Exemplo de Payload de Feedback
Aqui está um exemplo de uma mensagem de feedback seguindo um comando para definir vários pontos de potência:

<ClickableImage src="/img/generic/mqtt-example-feedback.png" alt="Imagem 1" maxWidth="450px" />

Este feedback demonstra o estado operacional atual do sistema após a execução dos pontos de ajuste, indicando os efeitos sobre a geração solar, armazenamento e interação geral com a rede.

## Versões MQTT Suportadas e Comportamento em Tópicos Não Autorizados
Ao usar MQTT, é importante considerar as diferenças nas especificações entre as versões 3.1, 3.1.1 e 5.0, particularmente em relação ao comportamento do broker quando os clientes publicam em tópicos não autorizados.

De acordo com a especificação MQTT 3.1.1 (veja a Especificação OASIS MQTT 3.1.1, seção MQTT-3.3.5-2), um broker deve encerrar a conexão assim que um cliente enviar um PUBLISH para um tópico para o qual não tem permissão. Esse comportamento pode levar a desconexões inesperadas para clientes que tentam publicar em tópicos mal configurados ou não autorizados.

Na MQTT 3.1, esse requisito não está presente. Quando um cliente publica em um tópico não autorizado sob esta versão, o broker geralmente ignora a mensagem (descarte silencioso) sem encerrar a conexão. Isso torna MQTT 3.1, em alguns casos, mais adequado quando a robustez contra erros de configuração ou permissões temporariamente ausentes é mais importante do que a aplicação estrita de segurança.

Embora MQTT 5.0 introduza a capacidade de trabalhar com códigos de razão (como PUBACK com um motivo de recusa), isso requer suporte tanto no lado do cliente quanto do servidor. Migrar para MQTT 5.0, portanto, envolve um esforço adicional de implementação.

__Consequências de Ignorar Compatibilidade:__
Se um cliente se conectar usando MQTT 3.1.1 e tentar publicar mensagens em tópicos não autorizados, o broker encerrará abruptamente a sessão. Isso pode levar à instabilidade, perda de conectividade ou aumento da carga devido a tentativas de reconexão repetidas.

__Abordagem Recomendada:__
Para sistemas onde os clientes podem (temporariamente) tentar publicar em tópicos não autorizados, ou onde o gerenciamento de erros não é rigorosamente implementado, recomendamos usar MQTT 3.1. Isso garante conexões mais estáveis e evita desconexões não intencionais durante a execução.